﻿#region License
/* ---------------------------------------------------------------- *
 *
 * This file is part of the Xcoordination Application Space
 * ("XcoAppSpace") http://www.xcoordination.com
 *
 * Copyright (C) 2009 Xcoordination http://www.xcoordination.com
 *
 * XcoAppSpace is free software; you can redistribute it and/or
 * modify it under the terms of version 2 of the GNU General
 * Public License as published by the Free Software Foundation.
 *
 * XcoAppSpace is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see http://www.gnu.org/licenses/
 * or write to the Free Software Foundation, Inc., 51 Franklin
 * Street, Fifth Floor, Boston, MA 02110-1301, USA.
 *
 * ---------------------------------------------------------------- */
#endregion

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Text;
using Microsoft.Ccr.Core;
using XcoAppSpaces.Contracts.Service;
using XcoAppSpaces.Contracts.Messaging;
using XcoAppSpaces.Contracts.Transport;

namespace XcoAppSpaces.Contracts.Communication
{
	/// <summary>
	/// Service for connecting to remote workers and handling the space's transport services, as well as communication errors.
	/// </summary>
	public interface IConnector : IXcoStatefulService, IDisposable
	{
		/// <summary>
		/// The local address of the space (in form hostname:port).
		/// </summary>
		string LocalAddress { get; }

		/// <summary>
		/// The list of registered communication services.
		/// </summary>
		IEnumerable<XcoServiceConfiguration<IXcoTransportService>> CommServices { get; }

		/// <summary>
		/// Port where communication errors are posted that are not caught by causalities.
		/// </summary>
		Port<XcoCommunicationError> Errors { get; }

		/// <summary>
		/// Events giving information about incoming and outgoing communication, e.g. for monitoring
		/// </summary>
		ICommunicationEvents CommunicationEvents { get; }

		/// <summary>
		/// Checks a certain address if it is the address of the local space. This is the case if the
		/// address is either NULL of if it is equal (ignoring case) to the local address.
		/// </summary>
		/// <param name="address">The address to be checked.</param>
		/// <returns>True if the address refers to the local space.</returns>
		bool IsLocal(string address);

		/// <summary>
		/// Establishes a connection to a worker that is running at a remote space. Returns information that
		/// can be used to generate proxy of the worker that allows posting messages that are automatically 
		/// transported to the worker.
		/// If the worker does't exist or the connection to the space cannot be established, an
		/// XcoCommunicationException is thrown.
		/// </summary>
		/// <typeparam name="TContract">The contract type of the worker to connect to.</typeparam>
		/// <param name="workerAddress">The address of the worker in den form "address/workername"</param>
		/// <param name="commServiceName">The name of the communication service that should be used to communicate with the worker (or null if the default communication service should be used).</param>
		/// <param name="credentials">The credentials that should be used to connect to the worker.</param>
		/// <returns>Information about the worker that can be used to generate a proxy to communicate with this worker.</returns>
		WorkerProxyInfo ConnectWorker<TContract>(string workerAddress, string commServiceName, ICredentials credentials)
			where TContract : IPort, new();

		/// <summary>
		/// Establishes a connection to a worker that is running at a remote space. Returns information that
		/// can be used to generate proxy of the worker that allows posting messages that are automatically 
		/// transported to the worker.
		/// If the worker does't exist or the connection to the space cannot be established, an
		/// XcoCommunicationException is thrown.
		/// </summary>
		/// <typeparam name="TContract">The contract type of the worker to connect to.</typeparam>
		/// <param name="name">The name of the worker.</param>
		/// <param name="address">The address of the space where the worker is running (in form hostname:port).</param>
		/// <param name="commServiceName">The name of the communication service that should be used to communicate with the worker (or null if the default communication service should be used).</param>
		/// <param name="credentials">The credentials that should be used to connect to the worker.</param>
		/// <returns>Information about the worker that can be used to generate a proxy to communicate with this worker.</returns>
		WorkerProxyInfo ConnectWorker<TContract>(string name, string address, string commServiceName, ICredentials credentials)
			where TContract : IPort, new();
	}
}